home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / fg / fgl402b / manuals.arj / USER09.DOC < prev    next >
Text File  |  1995-02-06  |  71KB  |  1,557 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Chapter 9
  8.  
  9.  
  10.  
  11.  
  12.  
  13. Image Files                                                                    
  14. 184   Fastgraph User's Guide
  15.  
  16.  
  17. Overview
  18.  
  19.      Within the context of Fastgraph, an image is a rectangular area
  20. containing some type of picture. An image might be something as simple as a
  21. pointing hand icon, or as detailed as the dashboard of a sports car. Fastgraph
  22. includes several routines to display, retrieve, and manipulate images. In this
  23. chapter we'll begin our discussion of images by looking at the PCX, GIF,
  24. FLI/FLC, and pixel run image file formats Fastgraph supports, as well as the
  25. routines available for displaying and creating image files in these formats.
  26.  
  27.  
  28. PCX Files
  29.  
  30.      The PCX file format was originally developed by ZSoft Corporation for
  31. their commercial paint program, PC Paintbrush. It has evolved into one of the
  32. more popular image file formats because so many products can read and write
  33. PCX files to at least some extent. Fastgraph includes routines for displaying
  34. and creating PCX files, as well as other PCX support functions.
  35.  
  36.      The fg_showpcx routine displays an image stored in a PCX file. It can
  37. position the image using the coordinate information in the PCX header, or such
  38. that its upper left corner is at the graphics cursor position on the active
  39. video page. The first argument to fg_showpcx is the name of the PCX file (it
  40. may include a path name), and its second argument is a bit mask that controls
  41. how the image is displayed. The file name must be terminated with a null
  42. character, so BASIC, FORTRAN, and Pascal programmers will need to store a zero
  43. byte as the last character of the file name string. The fg_showpcx routine
  44. cannot display PCX images in virtual buffers. A separate routine, fg_loadpcx,
  45. is provided for this purpose and will be described later in this section.
  46.  
  47.      In the current version of Fastgraph, only the low-order three bits (bits
  48. 0 to 2) of the bit mask argument are meaningful. The following table
  49. summarizes the meanings of these bits.
  50.  
  51.               Bit Value  Meaning
  52.  
  53.                0    0    Use palette values stored in the PCX file
  54.                0    1    Use the current palette settings
  55.                1    0    Display image at position indicated in PCX header
  56.                1    1    Display image at current graphics position
  57.                2    0    Display image data from the PCX file
  58.                2    1    Display image data from the fg_imagebuf buffer
  59.  
  60. All other bits are reserved and should be zero to guarantee compatibility with
  61. future releases. The fg_showpcx routine returns a value of 0 if successful, 1
  62. if the specified file wasn't found, and 2 if the file is not a PCX file.
  63.  
  64.      The fg_makepcx routine creates a PCX file from the specified rectangular
  65. region of the active video page or virtual buffer. Its first four arguments
  66. define the minimum x, maximum x, minimum y, and maximum y screen space
  67. coordinates of the region (the minimum x coordinate is reduced to a byte
  68. boundary if necessary). Its fifth argument is the name of the PCX file to
  69. create (it may include a path name). As with fg_showpcx, the file name must be
  70. terminated with a null character. If an identically named file exists, it is   
  71.                                                  Chapter 9:  Image Files   185
  72.  
  73. overwritten. The fg_makepcx routine returns a value of 0 if successful, and 1
  74. if the PCX file was not created.
  75.  
  76.      Example 9-1 uses fg_showpcx and fg_makepcx to create a new PCX file from
  77. selected rows of an existing 256-color 320x200 PCX file. As written, the
  78. program uses the file CORAL.PCX to create NEW.PCX, but it could easily be
  79. extended to work with any PCX files. The call to fg_showpcx displays the image
  80. in CORAL.PCX using the screen position and palette settings defined in the PCX
  81. file. After waiting for a keystroke, the program calls fg_makepcx to create a
  82. PCX file named NEW.PCX from pixel rows 80 through 99 of the original image. In
  83. case the program encounters any problems, it prints an error message before
  84. exiting.
  85.  
  86.                                  Example 9-1.
  87.  
  88.             #include <fastgraf.h>
  89.             #include <stdio.h>
  90.             #include <stdlib.h>
  91.             void main(void);
  92.  
  93.             void main()
  94.             {
  95.                int old_mode;
  96.                int read_status, write_status;
  97.  
  98.                fg_initpm();
  99.                if (fg_testmode(19,1) == 0) {
  100.                   printf("This program requires a 320 ");
  101.                   printf("x 200 MCGA graphics mode.\n");
  102.                   exit(1);
  103.                   }
  104.                old_mode = fg_getmode();
  105.                fg_setmode(19);
  106.  
  107.                read_status = fg_showpcx("CORAL.PCX",0);
  108.                fg_waitkey();
  109.                if (read_status == 0)
  110.                   write_status = fg_makepcx(0,319,80,99,"NEW.PCX");
  111.                else
  112.                   write_status = 1;
  113.  
  114.                fg_setmode(old_mode);
  115.                fg_reset();
  116.  
  117.                if (read_status == 1)
  118.                   printf("CORAL.PCX not found.\n");
  119.                else if (read_status == 2)
  120.                   printf("CORAL.PCX is not a PCX file.\n");
  121.                if (write_status == 1)
  122.                   printf("NEW.PCX not created.\n");
  123.             }
  124.  
  125.  
  126.      In the Tandy/PCjr 16-color graphics mode (mode 9) and the native EGA
  127. graphics modes (modes 13 through 16), the palette registers are not readable.
  128. Hence, fg_makepcx will use the default palette settings when used in these     
  129. 186   Fastgraph User's Guide
  130.  
  131. video modes on Tandy and EGA systems. Displaying a PCX file at a lower
  132. resolution (for example, a 640x480 PCX file at 320x200) will truncate the
  133. display on the right and on the bottom. This effectively displays the upper
  134. left corner of the image. The fg_showpcx and fg_makepcx routines have no
  135. effect in text video modes or in the Hercules low-resolution graphics mode.
  136.  
  137.      If you want to display a PCX file in a virtual buffer, you must use
  138. Fastgraph's fg_loadpcx routine instead of fg_showpcx. The fg_loadpcx
  139. parameters and return values are identical to those of fg_showpcx, but the
  140. image destination is a virtual buffer and not video memory. We found it
  141. preferable to create a separate function for loading PCX images into virtual
  142. buffers because PCX files closely resemble the structure of video memory. The
  143. fg_showpcx routine is optimized to take advantage of this, while fg_loadpcx
  144. must perform the additional task of converting the pixel data to the virtual
  145. buffer format.
  146.  
  147.      Example 9-2 shows how to display a PCX image in a virtual buffer with
  148. fg_loadpcx. The CORAL.PCX file used in this example is a 320x200 image, so the
  149. required virtual buffer size is 64,000 bytes. After creating and opening the
  150. virtual buffer, the program calls fg_loadpcx to display the image in the
  151. virtual buffer. If successful, it makes the image visible by copying the
  152. virtual buffer contents to the visual page using fg_vbpaste.
  153.  
  154.                                  Example 9-2.
  155.  
  156.             #include <fastgraf.h>
  157.             #include <stdio.h>
  158.             #include <stdlib.h>
  159.             #ifdef __TURBOC__
  160.             #include <alloc.h>
  161.             #else
  162.             #include <malloc.h>
  163.             #endif
  164.             void main(void);
  165.  
  166.             void main()
  167.             {
  168.                int handle;
  169.                int old_mode;
  170.                int status;
  171.             #ifdef FG32
  172.                char *buffer;
  173.             #else
  174.                char huge *buffer;
  175.             #endif
  176.  
  177.                fg_initpm();
  178.                if (fg_testmode(19,1) == 0) {
  179.                   printf("This program requires a 320 ");
  180.                   printf("x 200 MCGA graphics mode.\n");
  181.                   exit(1);
  182.                   }
  183.                old_mode = fg_getmode();
  184.                fg_setmode(19);
  185.                fg_vbinit();                                                    
  186.                                                  Chapter 9:  Image Files   187
  187.  
  188.             #ifdef FG32
  189.                buffer = (char *)malloc(64000);
  190.             #elif defined(__TURBOC__)
  191.                buffer = (char huge *)farmalloc(64000L);
  192.             #else
  193.                buffer = (char huge *)halloc(64000L,1);
  194.             #endif
  195.                if (buffer == NULL) {
  196.                   fg_setmode(old_mode);
  197.                   fg_reset();
  198.                   printf("Could not create the virtual buffer.\n");
  199.                   exit(1);
  200.                   }
  201.                handle = fg_vbdefine(buffer,320,200);
  202.                fg_vbopen(handle);
  203.  
  204.                status = fg_loadpcx("CORAL.PCX",0);
  205.                if (status == 0) {
  206.                   fg_vbpaste(0,319,0,199,0,199);
  207.                   fg_waitkey();
  208.                   }
  209.  
  210.                fg_vbclose();
  211.                fg_setmode(old_mode);
  212.                fg_reset();
  213.  
  214.                if (status == 1)
  215.                   printf("CORAL.PCX not found.\n");
  216.                else if (status == 2)
  217.                   printf("CORAL.PCX is not a PCX file.\n");
  218.             }
  219.  
  220.  
  221.      Because their structure parallels that of video memory, PCX files are
  222. specific to certain video modes. If you try to display a PCX file in an
  223. incompatible video mode, fg_showpcx will still display something, but it will
  224. be garbled. The following table summarizes the compatible video modes for PCX
  225. files.
  226.  
  227.                     If PCX file was     You can display
  228.                     created in mode     it in these modes
  229.  
  230.                     4, 5                4, 5
  231.                     6, 11               6, 11, 13-18, 28, 29
  232.                     9                   9
  233.                     13-18               13-18, 28, 29
  234.                     19-27               19-27
  235.                     28-29               13-18, 28, 29
  236.  
  237.      Unlike fg_showpcx, fg_loadpcx does not display a PCX image directly to
  238. video memory. The fg_loadpcx routine instead converts the mode-specific
  239. structure of the PCX file to the mode-independent virtual buffer format as it
  240. unpacks the image data. This overhead means fg_showpcx is faster than
  241. fg_loadpcx, but fg_loadpcx makes it possible to display any PCX file in any
  242. graphics video mode. The only problem occurs when displaying a PCX image with
  243. more colors than the current video mode supports (for example, displaying a    
  244. 188   Fastgraph User's Guide
  245.  
  246. 256-color PCX in a 16-color mode). In this case, fg_vbpaste will display
  247. pixels of color c in color c modulo n, where n is the number of colors
  248. available in the current video mode.
  249.  
  250.      The fg_pcxpal routine retrieves the palette of an image stored in a PCX
  251. file. Its first argument is a PCX file name, terminated by a zero byte as with
  252. fg_showpcx. Its second argument is the address of the array that will receive
  253. the PCX palette values. The palette values are returned as RGB color
  254. components, each between 0 and 63. The first three bytes of this array will
  255. contain the RGB values for color 0, the next three for color 1, and so forth.
  256. The array size in bytes must be at least three times the number of colors in
  257. the PCX image. If successful, the fg_pcxpal function return value is the
  258. number of colors in the PCX palette, either 16 or 256. The possible error
  259. return values are -1 (file not found) and -2 (file is not a PCX file).
  260.  
  261.      For video modes 18 and above, the fg_pcxpal palette values are suitable
  262. for use with fg_setdacs. For the native EGA graphics modes (13 to 16), the
  263. palette values must be converted into mode-specific values (with fg_maprgb)
  264. before being used with fg_palette or fg_palettes. If the PCX file includes an
  265. extended (256-color) palette, fg_pcxpal will return the values in the extended
  266. palette. Otherwise, it will return the values from the 16-color palette in the
  267. PCX header.
  268.  
  269.      Fastgraph's fg_pcxmode function determines the optimal video mode for
  270. displaying a PCX file. By optimal, we mean the compatible video mode having
  271. the lowest resolution larger than or equal to the image dimensions. The
  272. fg_pcxmode routine has a single argument -- the address of a buffer that
  273. contains a 128-byte PCX file header. Specific values defined in certain fields
  274. of the PCX header determine which video mode is optimal. A positive return
  275. value from fg_pcxmode represents the optimal video mode number. The possible
  276. error returns are -1 if the buffer does not contain a valid PCX header, and -2
  277. if fg_pcxmode cannot find any compatible video mode.
  278.  
  279.      Another useful PCX support function is fg_pcxrange, which returns the
  280. image position information from the PCX header. The first fg_pcxrange argument
  281. is the address of a buffer containing a 128-byte PCX file header. The
  282. remaining four arguments receive the minimum x, maximum x, minimum y, and
  283. maximum y values of the corresponding PCX image. You can use the image extents
  284. to determine the image dimensions -- for example, the width of a PCX image
  285. would be maximum_x - minimum_x + 1.
  286.  
  287.      How do we get the header from a PCX file into the buffer passed to
  288. fg_pcxmode or fg_pcxrange? The easiest way is with the fg_pcxhead function.
  289. Its first argument is the name of the PCX file from which to retrieve the
  290. header (as before, the file name must be null-terminated). The second argument
  291. is the address of the buffer that will receive the PCX header. The size of
  292. this buffer must be at least 128 bytes. If successful, fg_pcxhead returns
  293. zero. Otherwise, the return value is -1 if the specified file could not be
  294. opened, or -2 if the file is not a PCX file. After successfully reading the
  295. PCX header, you can pass it to fg_pcxmode to determine the optimal video mode
  296. for the PCX file. Full information about the 128-byte PCX file header appears
  297. in Appendix H.
  298.  
  299.      Example 9-3 uses Fastgraph's fg_pcxhead, fg_pcxmode, fg_pcxpal, and
  300. fg_pcxrange routines to obtain information about the CORAL.PCX file. It        
  301.                                                  Chapter 9:  Image Files   189
  302.  
  303. displays the optimal video mode number for displaying the image, the image
  304. dimensions, and the image's first 16 color palette values.
  305.  
  306.                                  Example 9-3.
  307.  
  308.     #include <fastgraf.h>
  309.     #include <stdio.h>
  310.     #include <stdlib.h>
  311.     void main(void);
  312.  
  313.     void main()
  314.     {
  315.        int i, j;
  316.        int mode, status;
  317.        int minx, maxx, miny, maxy;
  318.        unsigned char PCXpal[768];
  319.        unsigned char header[128];
  320.  
  321.        fg_initpm();
  322.        status = fg_pcxhead("CORAL.PCX",header);
  323.        if (status == -1) {
  324.           printf("Can't open CORAL.PCX.\n");
  325.           exit(1);
  326.           }
  327.        else if (status == -2) {
  328.           printf("CORAL.PCX is not a PCX file.\n");
  329.           exit(1);
  330.           }
  331.  
  332.        mode = fg_pcxmode(header);
  333.        printf("Optimal display mode is %d.\n",mode);
  334.  
  335.        fg_pcxrange(header,&minx,&maxx,&miny,&maxy);
  336.        printf("Image size is %d by %d pixels.\n",maxx-minx+1,maxy-miny+1);
  337.  
  338.        fg_pcxpal("CORAL.PCX",PCXpal);
  339.        printf("First 16 palette values are:\n");
  340.        j = 0;
  341.        for (i = 0; i < 16; i++) {
  342.           printf("  color %2d: R=%2d G=%2d B=%2d\n",
  343.              i,PCXpal[j],PCXpal[j+1],PCXpal[j+2]);
  344.           j += 3;
  345.           }
  346.     }
  347.  
  348.  
  349.  
  350. GIF Files
  351.  
  352.      The GIF file format was created by CompuServe, Inc., as a transmission
  353. format for images and graphics data across the CompuServe network. It has
  354. evolved into what is probably the most popular image file format in use today.
  355. GIF files are especially prevalent on bulletin boards and electronic data
  356. networks because their efficient image compression results in less storage
  357. space and faster transmission times than other image file formats. GIF,
  358. pronounced "jif", is an acronym for Graphics Interchange Format. The format is 
  359. 190   Fastgraph User's Guide
  360.  
  361. the copyright property of CompuServe, Inc., whose GIF specification "grants a
  362. limited, non-exclusive, royalty-free license for the use of the Graphics
  363. Interchange Format in computer software; computer software utilizing GIF must
  364. acknowledge ownership of the Graphics Interchange Format and its Service Mark
  365. by CompuServe, Inc., in user and technical documentation".
  366.  
  367.      Two GIF specifications, released in 1987 and 1989, are defined. The 1989
  368. specification (known as "89a") is a superset of the original 1987
  369. specification (known as "87a"). Fastgraph's GIF file display routine can
  370. handle either 87a or 89a files. For maximum portability, the GIF file creation
  371. routine always produces files conforming to the 87a specification.
  372.  
  373.      The fg_showgif routine displays an image stored in a GIF file. It can
  374. position the image using the coordinate information in the GIF header, or such
  375. that its upper left corner is at the graphics cursor position on the active
  376. video page or virtual buffer. The fg_showgif arguments are the same as for
  377. fg_showpcx, except the file name must of course reference a GIF file rather
  378. than a PCX file. Likewise, the fg_showgif return values are analogous to those
  379. of fg_showpcx.
  380.  
  381.      The fg_makegif routine creates a GIF file from the specified rectangular
  382. region of the active video page or virtual buffer. Its arguments and return
  383. value are analogous to those of fg_makepcx.
  384.  
  385.      Example 9-4 uses fg_showgif and fg_makegif to create a new GIF file from
  386. selected rows of an existing 256-color 320x200 GIF file. Similar to example
  387. 9-1, the program uses the file CORAL.GIF to create NEW.GIF, but it could
  388. easily be extended to work with any GIF files. The call to fg_showgif displays
  389. the image in CORAL.GIF using the screen position and palette settings defined
  390. in the GIF file. After waiting for a keystroke, the program calls fg_makegif
  391. to create a GIF file named NEW.GIF from pixel rows 80 through 99 of the
  392. original image. In case the program encounters any problems, it prints an
  393. error message before exiting.
  394.  
  395.                                  Example 9-4.
  396.  
  397.             #include <fastgraf.h>
  398.             #include <stdio.h>
  399.             #include <stdlib.h>
  400.             void main(void);
  401.  
  402.             void main()
  403.             {
  404.                int old_mode;
  405.                int read_status, write_status;
  406.  
  407.                fg_initpm();
  408.                if (fg_testmode(19,1) == 0) {
  409.                   printf("This program requires a 320 ");
  410.                   printf("x 200 MCGA graphics mode.\n");
  411.                   exit(1);
  412.                   }
  413.                old_mode = fg_getmode();
  414.                fg_setmode(19);
  415.  
  416.                read_status = fg_showgif("CORAL.GIF",0);                        
  417.                                                  Chapter 9:  Image Files   191
  418.  
  419.                fg_waitkey();
  420.                if (read_status == 0)
  421.                   write_status = fg_makegif(0,319,80,99,"NEW.GIF");
  422.                else
  423.                   write_status = 1;
  424.  
  425.                fg_setmode(old_mode);
  426.                fg_reset();
  427.  
  428.                if (read_status == 1)
  429.                   printf("CORAL.GIF not found.\n");
  430.                else if (read_status == 2)
  431.                   printf("CORAL.GIF is not a GIF file.\n");
  432.                if (write_status == 1)
  433.                   printf("NEW.GIF not created.\n");
  434.             }
  435.  
  436.  
  437.      Like fg_makepcx, the fg_makegif routine will use the default palette
  438. settings when running on Tandy and EGA systems. Displaying a GIF file at a
  439. lower resolution (for example, a 640x480 GIF file at 320x200) will truncate
  440. the display on the right and on the bottom. This effectively displays the
  441. upper left corner of the image. Unlike PCX files, GIF files do not exhibit
  442. compatibility problems between 16-color and 256-color graphics modes. When
  443. fg_showgif displays a 256-color GIF in a 16-color mode, it displays pixels of
  444. color c in color c modulo 16. The fg_showgif and fg_makegif routines have no
  445. effect in text video modes, or in CGA and Hercules graphics modes.
  446.  
  447.      Fastgraph includes additional GIF support routines analogous to those for
  448. PCX files. The fg_gifpal routine retrieves the palette of an image stored in a
  449. GIF file. If the GIF file includes a local palette for the first image,
  450. fg_gifpal will return the values from the local palette. Otherwise, fg_gifpal
  451. will return the values from the GIF file's global palette. The fg_gifmode
  452. function determines the optimal video mode for displaying a GIF file. The
  453. fg_gifrange routine returns the image position information from the GIF
  454. header. The fg_gifhead routine reads a GIF file's global header and first
  455. local header into a 23-byte array (full information about the headers appears
  456. in Appendix H). The parameters and return values for these routines are the
  457. same as for their PCX counterparts.
  458.  
  459.      Example 9-5 uses Fastgraph's fg_gifhead, fg_gifmode, fg_gifpal, and
  460. fg_gifrange routines to obtain information about the CORAL.GIF file. It
  461. displays the optimal video mode number for displaying the image, the image
  462. dimensions, and the image's first 16 palette values.
  463.  
  464.                                  Example 9-5.
  465.  
  466.     #include <fastgraf.h>
  467.     #include <stdio.h>
  468.     #include <stdlib.h>
  469.     void main(void);
  470.  
  471.     void main()
  472.     {
  473.        int i, j;
  474.        int mode, status;                                                       
  475. 192   Fastgraph User's Guide
  476.  
  477.        int minx, maxx, miny, maxy;
  478.        unsigned char GIFpal[768];
  479.        unsigned char header[23];
  480.  
  481.        fg_initpm();
  482.        status = fg_gifhead("CORAL.GIF",header);
  483.        if (status == -1) {
  484.           printf("Can't open CORAL.GIF.\n");
  485.           exit(1);
  486.           }
  487.        else if (status == -2) {
  488.           printf("CORAL.GIF is not a GIF file.\n");
  489.           exit(1);
  490.           }
  491.  
  492.        mode = fg_gifmode(header);
  493.        printf("Optimal display mode is %d.\n",mode);
  494.  
  495.        fg_gifrange(header,&minx,&maxx,&miny,&maxy);
  496.        printf("Image size is %d by %d pixels.\n",maxx-minx+1,maxy-miny+1);
  497.  
  498.        fg_gifpal("CORAL.GIF",GIFpal);
  499.        printf("First 16 palette values are:\n");
  500.        j = 0;
  501.        for (i = 0; i < 16; i++) {
  502.           printf("  color %2d: R=%2d G=%2d B=%2d\n",
  503.              i,GIFpal[j],GIFpal[j+1],GIFpal[j+2]);
  504.           j += 3;
  505.           }
  506.     }
  507.  
  508.  
  509.  
  510. FLI and FLC files
  511.  
  512.      FLI and FLC files (collectively called flic files) contain sequences of
  513. image frames that can be displayed in rapid succession to achieve the illusion
  514. of movement (this is called playing a flic file). FLI files are produced by
  515. Autodesk Animator and always have a 320x200 resolution, while FLC files are
  516. produced by Autodesk Animator Pro and can have any resolution. Fastgraph's
  517. flic file routines work with both FLI and FLC files, but they are restricted
  518. to 256-color graphics modes because flic files always contain 256-color
  519. images. The first frame of a flic file is usually a compressed version of the
  520. entire image, while later frames are compressed versions of the differences
  521. between that frame and the previous frame. This compression scheme is often
  522. called delta compression in flic file literature.
  523.  
  524.      Fastgraph includes both high-level and low-level routines for working
  525. with flic files. The most important high-level routine, fg_showflic, plays the
  526. entire contents of a flic file any number of times. It can position the image
  527. such that its upper left corner is at the screen origin or at the graphics
  528. cursor position on the active video page (flic files cannot be played in
  529. virtual buffers). The fg_showflic routine expects three arguments. The first
  530. is the flic file name, which may include a path name, but must be null-
  531. terminated. The second specifies the number of times to play the flic file. If
  532. the play count is zero, fg_showflic will play it continuously. The fg_showflic 
  533.                                                  Chapter 9:  Image Files   193
  534.  
  535. routine will stop playing the flic file if the Escape key is pressed. Note
  536. that this is the only way to stop playing the flic file if the play count is
  537. zero (continuous play).
  538.  
  539.      The third fg_showflic argument is a bit mask that controls how the image
  540. is displayed. In the current version of Fastgraph, only the low-order three
  541. bits (bits 0 to 2) of the bit mask argument are meaningful. The following
  542. table summarizes the meanings of these bits.
  543.  
  544.               Bit Value  Meaning
  545.  
  546.                0    0    Delay between frames as indicated in flic header
  547.                0    1    No delay between frames
  548.                1    0    Display image relative to screen origin
  549.                1    1    Display image relative to current graphics position
  550.                2    0    Display image data from the specified flic file
  551.                2    1    Display image data from the fg_imagebuf buffer
  552.  
  553. All other bits are reserved and should be zero to guarantee compatibility with
  554. future releases. The fg_showflic routine returns a value of 0 if successful, 1
  555. if the specified file wasn't found, and 2 if the file is not a flic file.
  556.  
  557.      Example 9-6 is a simple flic file player. It uses the standard VGA/MCGA
  558. 256-color graphics mode (mode 19) to play the flic file GLASS.FLI, one of the
  559. examples supplied with Autodesk Animator. The upper left corner of the flic
  560. file will be at the screen origin, with a delay between frames as defined in
  561. the flic file header.
  562.  
  563.                                  Example 9-6.
  564.  
  565.             #include <fastgraf.h>
  566.             #include <stdio.h>
  567.             void main(void);
  568.  
  569.             void main(void)
  570.             {
  571.                int status;
  572.  
  573.                fg_initpm();
  574.                fg_setmode(19);
  575.  
  576.                status = fg_showflic("GLASS.FLI",1,0);
  577.                if (status == 0) fg_waitkey();
  578.  
  579.                fg_setmode(3);
  580.                fg_reset();
  581.  
  582.                if (status == 1)
  583.                   printf("GLASS.FLI not found.\n");
  584.                else if (status == 2)
  585.                   printf("GLASS.FLI is not an FLI or FLC file.\n");
  586.             }
  587.  
  588.  
  589.      Fastgraph includes additional flic support routines similar to those for
  590. PCX and GIF files. The fg_flichead routine reads the specified flic file's     
  591. 194   Fastgraph User's Guide
  592.  
  593. 128-byte header (full information about the header appears in Appendix H). The
  594. fg_flicmode function determines the optimal video mode for playing a flic
  595. file. Its only argument is a 128-byte array containing a flic file header
  596. returned by fg_flichead. If successful, it returns the optimal video mode
  597. number for playing the flic image. If the array does not contain a valid flic
  598. file header, fg_flicmode returns -1. The fg_flicsize routine returns the image
  599. dimensions from the flic header. Its first argument is a 128-byte flic header
  600. array, and is remaining two arguments receive the image width and height in
  601. pixels. Example 9-7 uses these three routines to obtain information about the
  602. GLASS.FLI file. It displays the optimal video mode number for playing the flic
  603. file, as well as the image dimensions.
  604.  
  605.                                  Example 9-7.
  606.  
  607.           #include <fastgraf.h>
  608.           #include <stdio.h>
  609.           #include <stdlib.h>
  610.           void main(void);
  611.  
  612.           void main()
  613.           {
  614.              int mode, status;
  615.              int width, height;
  616.              unsigned char header[128];
  617.  
  618.              fg_initpm();
  619.              status = fg_flichead("GLASS.FLI",header);
  620.              if (status == -1) {
  621.                 printf("Can't open GLASS.FLI.\n");
  622.                 exit(1);
  623.                 }
  624.              else if (status == -2) {
  625.                 printf("GLASS.FLI is not a FLI or FLC file.\n");
  626.                 exit(1);
  627.                 }
  628.  
  629.              mode = fg_flicmode(header);
  630.              printf("Optimal display mode is %d.\n",mode);
  631.  
  632.              fg_flicsize(header,&width,&height);
  633.              printf("Image size is %d by %d pixels.\n",width,height);
  634.           }
  635.  
  636.  
  637.      Fastgraph's low-level flic routines provide the ability to display flic
  638. files one frame at a time. This is desirable when your program must perform
  639. other tasks between frames, or for playing two or more flic files at the same
  640. time. To use Fastgraph's low-level flic routines, call fg_flicopen for each
  641. flic file. The first fg_flicopen argument is the flic file name. The second
  642. argument is a 16-byte array that will receive a context descriptor for the
  643. flic file. You must create a context descriptor with fg_flicopen for each flic
  644. file you'll access with the low-level flic file routines (the number of flic
  645. files you can have open at any one time is limited by the FILES specifier in
  646. your CONFIG.SYS file). The context descriptor is then passed to other routines
  647. when accessing the flic file. If successful, fg_flicopen fills the context
  648. descriptor, positions the flic file at the first frame, and returns zero. The  
  649.                                                  Chapter 9:  Image Files   195
  650.  
  651. possible error return values are -1 (file not found) and -2 (file is not an
  652. FLI or FLC file).
  653.  
  654.      The fg_flicplay routine plays one or more frames from a flic file and
  655. leaves the file positioned at the beginning of the next frame. Its three
  656. arguments are the same as for fg_showflic except the first argument is a
  657. context descriptor instead of a flic file name. The fg_flicskip routine
  658. advances over flic file frames. Its first argument is the flic file's context
  659. descriptor, and its second argument is the number of frames to skip (if the
  660. frame count is negative, the file position is reset to the first frame). Both
  661. routines return the number of frames played, which may be less than the number
  662. of frames requested if the end-of-file is reached. Fastgraph's last low-level
  663. flic routine, fg_flicdone, closes a flic file previously opened with
  664. fg_flicopen. Its only argument is the flic file's context descriptor.
  665.  
  666.      Example 9-8 is similar to example 9-6, but it plays the GLASS.FLI file
  667. one frame at a time using Fastgraph's low-level flic routines. It opens the
  668. flic file with fg_flicopen, which returns a 16-byte context descriptor for the
  669. file. If the file was opened successfully, the program plays each frame by
  670. calling fg_flicplay in a loop, waiting for a keystroke between each frame
  671. (note that the bit mask passed to fg_flicplay has bit 0 set, as it's usually
  672. not too meaningful to delay between frames when playing frames individually).
  673. Eventually we'll reach the end-of-file, indicated by an fg_flicplay return
  674. value of zero. When this occurs, the program calls fg_flicdone and exits.
  675.  
  676.                                  Example 9-8.
  677.  
  678.             #include <fastgraf.h>
  679.             #include <stdio.h>
  680.             void main(void);
  681.  
  682.             void main(void)
  683.             {
  684.                int frames;
  685.                int status;
  686.                char context[16];
  687.  
  688.                fg_initpm();
  689.                fg_setmode(19);
  690.  
  691.                status = fg_flicopen("GLASS.FLI",context);
  692.                if (status == 0) {
  693.                   do {
  694.                      frames = fg_flicplay(context,1,1);
  695.                      fg_waitkey();
  696.                      }
  697.                   while (frames > 0);
  698.                   fg_flicdone(context);
  699.                   }
  700.  
  701.                fg_setmode(3);
  702.                fg_reset();
  703.  
  704.                if (status == -1)
  705.                   printf("GLASS.FLI not found.\n");
  706.                else if (status == -2)                                          
  707. 196   Fastgraph User's Guide
  708.  
  709.                   printf("GLASS.FLI is not an FLI or FLC file.\n");
  710.             }
  711.  
  712.  
  713.  
  714. Pixel Run Files
  715.  
  716.      Fastgraph also provides its own mode-independent image file format called
  717. pixel run format. Pixel run files are useful in programs that must run in
  718. different video modes (but with the same resolution) because you can use the
  719. same image files for two-color modes as for 256-color modes. Two variations of
  720. the pixel run format exist -- standard pixel run files (SPR files) and packed
  721. pixel run files (PPR files). The packed pixel run format does not support 256-
  722. color images but will produce a smaller file if the image has 16 colors or
  723. less. Pixel run files do not include a header or any color palette
  724. information.
  725.  
  726.      The best way to illustrate the pixel run file format is with an example.
  727. Suppose we want to display a small triangle whose perimeter is a different
  728. color than its interior. To create the standard pixel run equivalent of this
  729. image, we must inscribe the triangle in a rectangular area. Hence, the pixel
  730. representation of our triangle might appear as shown here:
  731.  
  732.                                . . . . * . . . .
  733.                                . . . * x * . . .
  734.                                . . * x x x * . .
  735.                                . * x x x x x * .
  736.                                * * * * * * * * *
  737.  
  738.      As shown in this diagram, our triangle image is nine pixels wide at its
  739. base and five pixels high. The pixels indicated by an asterisk (*) are the
  740. triangle's perimeter, while those indicated by an x represent its interior
  741. points. The pixels shown as periods (.) are not part of the triangle itself,
  742. but they are part of the image. In this example, we can treat them as
  743. background pixels.
  744.  
  745.      If we start at the lower left corner of the image and proceed to the
  746. right, we could represent the first row of the image as nine pixels of color
  747. "asterisk". Such a group of consecutive identically colored pixels is called a
  748. pixel run, so a single pixel run describes the first row of the image. The row
  749. above this one is a bit more complex. It consists of five pixel runs: one
  750. pixel of color "period", followed by one of color "asterisk", then five of
  751. color "x", one of color "asterisk", and finally one of color "period".
  752.  
  753.      While we could construct separate pixel runs for each row of the image,
  754. notice that three of the five rows in our triangle begin with the same color
  755. pixel as the rightmost pixel in the previous row. Fastgraph's pixel run
  756. formats let you take advantage of this property by allowing pixel runs to wrap
  757. from one row to the next. This means we can represent the pixel run of color
  758. "period" extending from the right side of the second row to the left side of
  759. the third row as a single run of three pixels.
  760.  
  761.      An standard pixel run (SPR) file is nothing more than such a sequence of
  762. (color,count) pairs, as shown in the following diagram.                        
  763.                                                  Chapter 9:  Image Files   197
  764.  
  765.                           byte 0   color for run 1
  766.  
  767.                                1   count for run 1
  768.  
  769.                                2   color for run 2
  770.  
  771.                                3   count for run 2
  772.  
  773.  
  774.  
  775.  
  776.  
  777.                             2n-2   color for run n
  778.  
  779.                             2n-1   count for run n
  780.  
  781.  
  782. Each color is a value between 0 and 255 specifying the color index for that
  783. pixel run. Each count is a value between 0 and 255 specifying the length in
  784. pixels of that pixel run. If a single run exceeds 255 pixels, it must be
  785. broken into two or more runs. For example, we could represent a pixel run of
  786. length 265 as a run of length 255 followed by a run of length 10 of the same
  787. color. Note that the space in bytes needed to store an SPR image is twice the
  788. number of runs.
  789.  
  790.      Fastgraph's fg_showspr routine displays an SPR file. Its first argument
  791. is the name of the file containing the image (it may include a path name). The
  792. file name must be terminated with a null character, so BASIC, FORTRAN, and
  793. Pascal programmers will need to store a zero byte as the last character of the
  794. file name string. The second argument is the width in pixels of the image. The
  795. fg_showspr routine displays the image such that its lower left corner is at
  796. the graphics cursor position. The possible return values for fg_showspr are
  797. success (0) and file not found (1). To create an SPR file, use the fg_makespr
  798. routine. Its arguments and return values are the same as for fg_makepcx and
  799. fg_makegif.
  800.  
  801.      Example 9-9 uses fg_showspr and fg_makespr to create a new SPR file from
  802. selected rows of an existing 16-color 320x200 SPR file. Similar to examples
  803. 9-1 and 9-4, the program uses the file CORAL.SPR to create NEW.SPR, but it
  804. could easily be extended to work with any SPR files. The call to fg_move to
  805. establishes the lower left corner of the screen as the graphics cursor
  806. position (contrast this with the upper left corner being the reference point
  807. for PCX, GIF, and flic files). Then program then calls fg_showspr to display
  808. the image. After waiting for a keystroke, the program calls fg_makespr to
  809. create an SPR file named NEW.SPR from pixel rows 80 through 99 of the original
  810. image. In case the program encounters any problems, it prints an error message
  811. before exiting.
  812.  
  813.                                  Example 9-9.
  814.  
  815.             #include <fastgraf.h>
  816.             #include <stdio.h>
  817.             #include <stdlib.h>
  818.             void main(void);
  819.  
  820.             void main()                                                        
  821. 198   Fastgraph User's Guide
  822.  
  823.             {
  824.                int new_mode, old_mode;
  825.                int read_status, write_status;
  826.  
  827.                fg_initpm();
  828.                new_mode = fg_bestmode(320,200,1);
  829.                if (new_mode < 0 || new_mode == 12) {
  830.                   printf("This program requires a 320 ");
  831.                   printf("x 200 color graphics mode.\n");
  832.                   exit(1);
  833.                   }
  834.                old_mode = fg_getmode();
  835.                fg_setmode(new_mode);
  836.                fg_move(0,199);
  837.  
  838.                read_status = fg_showspr("CORAL.SPR",320);
  839.                fg_waitkey();
  840.                if (read_status == 0)
  841.                   write_status = fg_makespr(0,319,80,99,"NEW.SPR");
  842.                else
  843.                   write_status = 1;
  844.  
  845.                fg_setmode(old_mode);
  846.                fg_reset();
  847.  
  848.                if (read_status == 1)
  849.                   printf("CORAL.SPR not found.\n");
  850.                if (write_status == 1)
  851.                   printf("NEW.SPR not created.\n");
  852.             }
  853.  
  854.  
  855.      If you have an image that only uses the first 16 color indices (0 to 15),
  856. you can use Fastgraph's packed pixel run (PPR) image format. This format packs
  857. two color values into each color byte, so it takes three bytes instead of four
  858. to represent two pixel runs. This means a PPR file is 25% smaller than its SPR
  859. equivalent. In each set of three bytes, the high four bits of the first byte
  860. contain the color of the first run, and the low four bits contain the color of
  861. the second run. The second byte contains the length of the first run, and the
  862. third byte contains the length of the second run.
  863.  
  864.      The following diagram illustrates the structure of the packed pixel file.
  865. In this example, the file is assumed to contain n pixel runs, where n is an
  866. even number. If n is odd, the byte offset for the last element is 3n/2
  867. (truncated) instead of 3n/2-1, and the low four bits of the last color byte
  868. (that is, the color for pixel run n+1) are ignored.
  869.  
  870.                        7                4   3                0
  871.  
  872.                byte 0    color for run 1     color for run 2
  873.  
  874.                     1              count for run 1
  875.  
  876.                     2              count for run 2
  877.  
  878.                     3    color for run 3     color for run 4                   
  879.                                                  Chapter 9:  Image Files   199
  880.  
  881.  
  882.                     4              count for run 3
  883.  
  884.                     5              count for run 4
  885.  
  886.  
  887.  
  888.  
  889.  
  890.                3n/2-3   color for run n-1    color for run n
  891.  
  892.                3n/2-2             count for run n-1
  893.  
  894.                3n/2-1              count for run n
  895.  
  896.  
  897.      The structure of the PPR file allows for color values between 0 and 15,
  898. and run lengths between 0 and 255. The space in bytes needed to store an image
  899. in PPR format is 1.5 times the number of runs, compared to twice the number of
  900. runs for the SPR format.
  901.  
  902.      The fg_showppr and fg_makeppr routines display and create PPR files,
  903. respectively. Their arguments and return values are the same as those of
  904. fg_showspr and fg_makespr. If we wanted to display PPR files instead of SPR
  905. files in example 9-9, all that's necessary is changing the fg_showspr and
  906. fg_makespr calls to fg_showppr and fg_makeppr.
  907.  
  908.      Fastgraph's fg_dispfile routine displays both SPR and PPR files. The
  909. first of its three arguments is the name of the image file (it may include a
  910. path name). The file name must be terminated with a null character, so BASIC,
  911. FORTRAN, and Pascal programmers will need to store a zero byte as the last
  912. character of the file name string. The second argument is the image width in
  913. pixels, and the third argument defines the image format (that is, SPR or PPR).
  914. As with other pixel run display routines, fg_dispfile displays the image such
  915. that its lower left corner is at the graphics cursor position.
  916.  
  917.      Example 9-10 illustrates how to use fg_dispfile to display an image
  918. stored in a pixel run file. The program displays two identical images, one in
  919. an SPR file and the other in a PPR file. Each image is a picture of the sea
  920. floor and some coral, as might be used for the background in an aquarium. The
  921. program runs in a 320x200 graphics mode, and the images fill the entire
  922. screen.
  923.  
  924.      The SPR image is in file CORAL.SPR. The program uses fg_move to establish
  925. the lower left corner of the screen as the graphics cursor position and then
  926. calls fg_dispfile to display the image. The value of fg_dispfile's third
  927. argument tells Fastgraph the image format. A value of 0 indicates the file
  928. contains an image in SPR format, while a value of 1 indicates an image in PPR
  929. format. As mentioned earlier, the image fills the entire screen, so its width
  930. is 320 pixels.
  931.  
  932.      After waiting for a keystroke, the program clears the previous image from
  933. the screen and then calls fg_dispfile to display the PPR image from the file
  934. CORAL.PPR. The program leaves the second image on the screen until another
  935. keypress, at which time it restores the original video mode and screen
  936. attributes and returns to DOS.                                                 
  937. 200   Fastgraph User's Guide
  938.  
  939.  
  940.                                  Example 9-10.
  941.  
  942.                  #include <fastgraf.h>
  943.                  #include <stdio.h>
  944.                  #include <stdlib.h>
  945.                  void main(void);
  946.  
  947.                  void main()
  948.                  {
  949.                     int old_mode, new_mode;
  950.  
  951.                     fg_initpm();
  952.                     new_mode = fg_bestmode(320,200,1);
  953.                     if (new_mode < 0 || new_mode == 12) {
  954.                        printf("This program requires a 320 ");
  955.                        printf("x 200 color graphics mode.\n");
  956.                        exit(1);
  957.                        }
  958.  
  959.                     old_mode = fg_getmode();
  960.                     fg_setmode(new_mode);
  961.  
  962.                     fg_move(0,199);
  963.                     fg_dispfile("CORAL.SPR",320,0);
  964.                     fg_waitkey();
  965.  
  966.                     fg_erase();
  967.                     fg_dispfile("CORAL.PPR",320,1);
  968.                     fg_waitkey();
  969.  
  970.                     fg_setmode(old_mode);
  971.                     fg_reset();
  972.                  }
  973.  
  974.  
  975.      The SNAPSHOT utility distributed with Fastgraph is a terminate and stay
  976. resident program (TSR) that can capture graphics mode screen images and save
  977. them in SPR files. Thus, you can easily create files with SNAPSHOT and display
  978. them with fg_showspr or fg_dispfile. Another TSR utility, GrabRGB, is useful
  979. for capturing RGB color values from 256-color images. Appendix A contains
  980. complete descriptions of the SNAPSHOT and GrabRGB utilities.
  981.  
  982.  
  983. Display Patterns
  984.  
  985.      Example 9-10 works well in the graphics video modes with 16 or 256
  986. available colors. However, in the four-color CGA graphics modes the resulting
  987. image is not too good because of our limited color choices, and it would look
  988. even worse in the Hercules graphics mode. The Fastgraph routine fg_pattern
  989. allows you to associate a dither pattern (actually, any pixel sequence) with
  990. one of Fastgraph's 256 color indices appearing in a pixel run map. When
  991. displaying an SPR or PPR file, Fastgraph will use the pattern associated with
  992. that color index instead of displaying the color itself.                       
  993.                                                  Chapter 9:  Image Files   201
  994.  
  995.      The fg_pattern routine requires two integer arguments -- a color index
  996. (between 0 and 255) and the display pattern defined for that color index. A
  997. display pattern's structure resembles the structure of video memory and is
  998. thus dependent on the current video mode. The following sections list the
  999. initial display patterns and explain how to construct new display patterns for
  1000. different graphics video modes.
  1001.  
  1002. CGA four-color graphics modes
  1003.  
  1004.      In the four-color CGA graphics modes (modes 4 and 5), the display pattern
  1005. consists of an 8-bit shift count followed by an 8-bit pixel pattern. Each
  1006. pixel assumes a value between 0 and 3, so the pattern represents four pixels.
  1007. In even-numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-
  1008. numbered pixel rows, Fastgraph rotates the original pattern to the left by the
  1009. number of bits specified by the shift count.
  1010.  
  1011.      For example, if we are using the default CGA color palette, we could
  1012. create a darker shade of cyan by alternating cyan pixels (color 1, 01 binary)
  1013. with white pixels (color 3, 11 binary), as shown here:
  1014.  
  1015.  
  1016.                                   01 11 01 11
  1017.  
  1018.  
  1019. If we convert this pixel pattern to its hexadecimal equivalent, we get the
  1020. value 77.
  1021.  
  1022.      To complete the display pattern, we need to determine the shift count. If
  1023. we use a shift count of zero, the resulting display will simply be a series of
  1024. cyan and white vertical lines. What we really need is a checkerboard effect
  1025. where a white pixel is above and below each cyan pixel, and vice versa. If we
  1026. rotate the pattern one pixel (two bits) to the left, we will achieve the
  1027. desired effect. That is, a shift count of two produces the following pixel
  1028. patterns:
  1029.  
  1030.                        even-numbered rows   01 11 01 11
  1031.                         odd-numbered rows   11 01 11 01
  1032.  
  1033. Combining the shift count with the pixel pattern yields the display pattern
  1034. 0277 hex. The shift count is normally a multiple of two; note that a zero
  1035. shift count results in the same pattern being applied to all pixel rows.
  1036.  
  1037.      For the CGA four-color graphics modes, fg_setmode establishes the
  1038. following initial display patterns:
  1039.  
  1040.                        color       shift count    hexadecimal
  1041.                        index       and pattern    equivalent
  1042.  
  1043.                          0         0 00000000        0000
  1044.                          1         0 01010101        0055
  1045.                          2         0 10101010        00AA
  1046.                          3         0 11111111        00FF
  1047.  
  1048. These values are repeated as necessary to define color indices 4 to 255. That
  1049. is, colors 4, 8, 12, ... , 252 use the same defaults as color 0. Colors 5, 9,
  1050. 13, ... , 253 use the same defaults as color 1, and so forth. Also note that   
  1051. 202   Fastgraph User's Guide
  1052.  
  1053. pattern 0000 represents four pixels of color 0, 0055 represents four pixels of
  1054. color 1, 00AA represents four pixels of color 2, and 00FF represents four
  1055. pixels of color 3.
  1056.  
  1057. CGA two-color graphics mode
  1058.  
  1059.      In the two-color CGA graphics mode (mode 6), the display pattern also
  1060. consists of an 8-bit shift count followed by an 8-bit pixel pattern. Each
  1061. pixel assumes the value 0 or 1, so the pattern represents eight pixels. In
  1062. even-numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-
  1063. numbered pixel rows, Fastgraph rotates the original pattern to the left by the
  1064. number of bits specified by the shift count.
  1065.  
  1066.      For example, we could create a lighter shade of white by alternating
  1067. black pixels (color 0) with white pixels (color 1), as shown here:
  1068.  
  1069.  
  1070.                                 0 1 0 1 0 1 0 1
  1071.  
  1072.  
  1073. If we convert this pixel pattern to its hexadecimal equivalent, we get the
  1074. value 55.
  1075.  
  1076.      To complete the display pattern, we need to determine the shift count. We
  1077. must rotate the pattern one pixel (one bit) to the left to achieve the
  1078. checkerboard effect as in the CGA four color graphics modes. That is, a shift
  1079. count of one produces the following pixel patterns:
  1080.  
  1081.                      even-numbered rows   0 1 0 1 0 1 0 1
  1082.                       odd-numbered rows   1 0 1 0 1 0 1 0
  1083.  
  1084. Combining the shift count with the pixel pattern yields the display pattern
  1085. 0155 hex.
  1086.  
  1087.      For the CGA two-color graphics mode, fg_setmode establishes the initial
  1088. display patterns such that all even-numbered color indices are assigned the
  1089. value 0000, while all odd-numbered color indices are assigned the value 00FF.
  1090. Note that pattern 0000 represents eight pixels of color 0, and 00FF represents
  1091. eight pixels of color 1.
  1092.  
  1093. Tandy/PCjr 16-color graphics mode
  1094.  
  1095.      In the Tandy/PCjr 16-color graphics mode (mode 9), the display pattern
  1096. also consists of an 8-bit shift count followed by an 8-bit pixel pattern. Each
  1097. pixel assumes a value between 0 and 15, so the pattern represents two pixels.
  1098. In even-numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-
  1099. numbered pixel rows, Fastgraph rotates the original pattern to the left by the
  1100. number of bits specified by the shift count.
  1101.  
  1102.      For example, we could create a lighter shade of blue by alternating blue
  1103. pixels (color 1, 0001 binary) with white pixels (color 15, 1111 binary), as
  1104. shown here:
  1105.  
  1106.  
  1107.                                    0001 1111                                   
  1108.                                                  Chapter 9:  Image Files   203
  1109.  
  1110.  
  1111. If we convert this pixel pattern to its hexadecimal equivalent, we get the
  1112. value 1F.
  1113.  
  1114.      To complete the display pattern, we need to determine the shift count.
  1115. Using the same process as in the CGA graphics modes, we must rotate the
  1116. pattern one pixel (four bits) to the left to achieve the checkerboard effect.
  1117. That is, a shift count of four produces the following pixel patterns:
  1118.  
  1119.                         even-numbered rows   0001 1111
  1120.                          odd-numbered rows   1111 0001
  1121.  
  1122. Combining the shift count with the pixel pattern yields the display pattern
  1123. 041F hex. The shift count is normally zero or four; note that a zero shift
  1124. count results in the same pattern being applied to all pixel rows.
  1125.  
  1126.      For the Tandy/PCjr 16-color graphics modes, fg_setmode establishes the
  1127. initial display patterns such that color 0 is assigned the value 0000 (two
  1128. pixels of color 0), color 1 is assigned the value 0011 (two pixels of color
  1129. 1), color 2 is assigned the value 0022 (two pixels of color 2), and so forth.
  1130. These values are repeated as necessary to define color indices 16 to 255. That
  1131. is, colors 0, 16, 32, ... , 240 use the same defaults as color 0. Colors 1,
  1132. 17, 33, ... , 241 use the same defaults as color 1, and so forth.
  1133.  
  1134. Hercules graphics modes
  1135.  
  1136.      The structure of the display patterns for the Hercules graphics modes
  1137. (modes 11 and 12) is the same as two of the CGA graphics modes. For the
  1138. standard Hercules graphics mode (mode 11), please refer to the discussion of
  1139. CGA two-color (mode 6) display patterns. For the low-resolution Hercules
  1140. graphics mode (mode 12), please refer to the discussion of the CGA four-color
  1141. (mode 4) display patterns.
  1142.  
  1143. EGA/VGA/SVGA 16-color graphics modes
  1144.  
  1145.      In the EGA/VGA/SVGA 16-color graphics modes (modes 13 to 16, 18, 28, and
  1146. 29), the display pattern consists of two 4-bit color values (for consistency
  1147. with the other video modes, we still pass the display pattern as a 16-bit or
  1148. 32-bit quantity). Each pixel assumes a value between 0 and 15 (0 and 5 in the
  1149. EGA monochrome graphics mode), so the pattern represents two pixels. In even-
  1150. numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-numbered
  1151. pixel rows, Fastgraph rotates the original pattern one pixel (four bits) to
  1152. the left.
  1153.  
  1154.      For example, we could create a lighter shade of blue by alternating blue
  1155. pixels (color 1, 0001 binary) with white pixels (color 15, 1111 binary), as
  1156. shown here:
  1157.  
  1158.  
  1159.                                    0001 1111
  1160.  
  1161.  
  1162. If we convert this pixel pattern to its hexadecimal equivalent, we get the
  1163. value 1F. The implied four-bit shift count produces the following pixel
  1164. patterns:                                                                      
  1165. 204   Fastgraph User's Guide
  1166.  
  1167.                         even-numbered rows   0001 1111
  1168.                          odd-numbered rows   1111 0001
  1169.  
  1170. Extending the pixel pattern to a 16-bit or 32-bit quantity yields the display
  1171. pattern 001F hex.
  1172.  
  1173.      For the EGA/VGA/SVGA 16-color graphics modes, fg_setmode establishes the
  1174. initial display patterns such that color 0 is assigned the value 0000 (two
  1175. pixels of color 0), color 1 is assigned the value 0011 (two pixels of color
  1176. 1), color 2 is assigned the value 0022 (two pixels of color 2), and so forth.
  1177. These values are repeated as necessary to define color indices 16 to 255. That
  1178. is, colors 0, 16, 32, ... , 240 use the same defaults as color 0. Colors 1,
  1179. 17, 33, ... , 241 use the same defaults as color 1, and so forth.
  1180.  
  1181. MCGA/VGA 2-color graphics mode
  1182.  
  1183.      In the two-color MCGA/VGA graphics mode (mode 17), the display pattern
  1184. consists of two 1-bit color values (for consistency with the other video
  1185. modes, we still pass the display pattern as a 16-bit or 32-bit quantity). Each
  1186. pixel assumes the value 0 or 1, so the pattern represents two pixels. In even-
  1187. numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-numbered
  1188. pixel rows, Fastgraph rotates the original pattern one pixel (one bit) to the
  1189. left.
  1190.  
  1191.      For example, we could create a lighter shade of white by alternating
  1192. black pixels (color 0) with white pixels (color 1), as shown here:
  1193.  
  1194.  
  1195.                                       0 1
  1196.  
  1197.  
  1198. If we convert this pixel pattern to its hexadecimal equivalent, we get the
  1199. value 01. The implied one-bit shift count produces the following pixel
  1200. patterns:
  1201.  
  1202.                            even-numbered rows   0 1
  1203.                             odd-numbered rows   1 0
  1204.  
  1205. Extending the pixel pattern to a 16-bit or 32-bit quantity yields the display
  1206. pattern 0001 hex.
  1207.  
  1208.      For the VGA/MCGA two-color graphics mode, fg_setmode establishes the
  1209. initial display patterns such that all even-numbered color indices are
  1210. assigned the value 0000 (two pixels of color 0), while all odd-numbered color
  1211. indices are assigned the value 0003 (11 binary, or two pixels of color 1).
  1212.  
  1213. 256-color graphics modes
  1214.  
  1215.      The 256-color graphics modes (modes 19 through 27) offer 262,144
  1216. different colors, so dithering is seldom (if ever) required. For this reason,
  1217. fg_pattern has no effect in these video modes.                                 
  1218.                                                  Chapter 9:  Image Files   205
  1219.  
  1220. An example
  1221.  
  1222.      Example 9-11 illustrates the use of display patterns in several graphics
  1223. modes. This program runs in any 320x200 color graphics mode and displays the
  1224. CORAL.PPR image with one or more of the color indices redefined. If the
  1225. program runs in the standard CGA four-color mode (mode 4), it redefines the
  1226. first 16 display patterns using the fg_pattern routine and the values in the
  1227. CGApatterns array. In the Tandy/PCjr 16-color graphics mode (mode 9) and the
  1228. EGA low-resolution graphics mode (mode 13), the program redefines color index
  1229. 15 to produce an alternating gray and white dither pattern. In the MCGA 256-
  1230. color mode (mode 19), display patterns are not available, so the program uses
  1231. fg_setrgb to define color index 15 as slightly darker shade of gray than the
  1232. default for color 7.
  1233.  
  1234.                                  Example 9-11.
  1235.  
  1236.                 #include <fastgraf.h>
  1237.                 #include <stdio.h>
  1238.                 #include <stdlib.h>
  1239.                 void main(void);
  1240.  
  1241.                 int CGApatterns[] = {
  1242.                    0x0000,0x00FF,0x00FF,0x00FF,
  1243.                    0x02BB,0x0000,0x0222,0x0255,
  1244.                    0x00FF,0x00FF,0x00FF,0x0055,
  1245.                    0x00AA,0x00AA,0x00FF,0x0277
  1246.                    };
  1247.  
  1248.                 void main()
  1249.                 {
  1250.                    int color;
  1251.                    int old_mode, new_mode;
  1252.  
  1253.                    fg_initpm();
  1254.                    new_mode = fg_bestmode(320,200,1);
  1255.                    if (new_mode < 0 || new_mode == 12) {
  1256.                       printf("This program requires a 320 ");
  1257.                       printf("x 200 color graphics mode.\n");
  1258.                       exit(1);
  1259.                       }
  1260.  
  1261.                    old_mode = fg_getmode();
  1262.                    fg_setmode(new_mode);
  1263.  
  1264.                    if (new_mode == 4) {
  1265.                       fg_palette(0,0);
  1266.                       for (color = 0; color < 16; color++)
  1267.                          fg_pattern(color,CGApatterns[color]);
  1268.                       }
  1269.                    else if (new_mode == 9 || new_mode == 13)
  1270.                       fg_pattern(15,0x04F7);
  1271.                    else
  1272.                       fg_setrgb(15,38,38,38);
  1273.  
  1274.                    fg_move(0,199);
  1275.                    fg_showppr("CORAL.PPR",320);                                
  1276. 206   Fastgraph User's Guide
  1277.  
  1278.                    fg_waitkey();
  1279.  
  1280.                    fg_setmode(old_mode);
  1281.                    fg_reset();
  1282.                 }
  1283.  
  1284.  
  1285.  
  1286. Controlling the Image Buffer Size
  1287.  
  1288.      By default, all of Fastgraph's image file display and creation routines
  1289. use an internal 4,096-byte buffer. This buffer provides an intermediate
  1290. storage area, making it possible to perform more efficient buffered I/O when
  1291. reading or writing the image files. The fg_imagebuf routine lets you define
  1292. your own buffer for this purpose (the buffer size is limited to 64K bytes in
  1293. real mode and 16-bit protected mode). Larger buffers generally make image
  1294. display and creation faster. This is especially true in protected mode and
  1295. when playing flic files. Calling fg_setmode resets the fg_imagebuf buffer to
  1296. its default 4K size.
  1297.  
  1298.      The fg_imagebuf routine does not allocate storage for the internal
  1299. buffer. Rather, it just defines the array or dynamically allocated memory
  1300. block to be used as the buffer. The first argument passed to fg_imagebuf is
  1301. the address of this array or memory block, and the second argument is the
  1302. internal buffer size in bytes, represented as an unsigned integer. In 32-bit
  1303. modes, the address is passed as an ordinary near pointer, while in 16-bit
  1304. modes it is passed as a far (segmented) pointer. Fastgraph uses a far pointer
  1305. in 16-bit modes to avoid wasting valuable space in the default data segment,
  1306. and it almost always results in the ability to use a larger buffer. In real
  1307. mode Pascal programs, the space for the internal buffer must be allocated
  1308. dynamically with the GetMem procedure because it provides the only way to pass
  1309. something by far reference in Pascal. Protected mode Pascal programs can use
  1310. either GetMem or the GlobalAllocPtr function to allocate the buffer memory.
  1311. BASIC programs must pass the image buffer as a fixed-length string.
  1312.  
  1313.      Example 9-12 shows how to use fg_imagebuf to define a larger buffer when
  1314. displaying the CORAL.PCX file. In this example, we'll use a 20,000-byte static
  1315. array as the image buffer. This size was chosen because it's larger than the
  1316. PCX file size, so fg_showpcx can read the entire PCX file in one pass.
  1317.  
  1318.                                  Example 9-12.
  1319.  
  1320.                  #include <fastgraf.h>
  1321.                  #include <stdio.h>
  1322.                  #include <stdlib.h>
  1323.                  void main(void);
  1324.  
  1325.                  #ifdef FG32
  1326.                  char buffer[20000];
  1327.                  #else
  1328.                  char far buffer[20000];
  1329.                  #endif
  1330.  
  1331.                  void main()
  1332.                  {
  1333.                     int old_mode;                                              
  1334.                                                  Chapter 9:  Image Files   207
  1335.  
  1336.  
  1337.                     fg_initpm();
  1338.                     if (fg_testmode(19,1) == 0) {
  1339.                        printf("This program requires a 320 ");
  1340.                        printf("x 200 MCGA graphics mode.\n");
  1341.                        exit(1);
  1342.                        }
  1343.                     old_mode = fg_getmode();
  1344.                     fg_setmode(19);
  1345.                     fg_imagebuf(buffer,20000);
  1346.                     fg_showpcx("CORAL.PCX",0);
  1347.                     fg_waitkey();
  1348.  
  1349.                     fg_setmode(old_mode);
  1350.                     fg_reset();
  1351.                  }
  1352.  
  1353.  
  1354.      You don't need to create separate buffers for each image you display or
  1355. create. Once you define an internal image buffer with fg_imagebuf, Fastgraph
  1356. will use that buffer until your program exits, or until you call fg_imagebuf
  1357. with a buffer size equal to zero.
  1358.  
  1359.      It's also possible to display PCX, GIF, and FLI/FLC images directly from
  1360. the buffer pointed to by fg_imagebuf. This can be quite useful, for instance,
  1361. when we need to display the same image file several times because we only read
  1362. the file from disk once. To do this, set bit 2 of the flags parameter when
  1363. using Fastgraph's PCX, GIF, or FLI/FLC image display routines. This tells
  1364. Fastgraph to retrieve the image data from the fg_imagebuf buffer rather than
  1365. from the file itself. In protected mode applications, using this method
  1366. usually provides better performance, especially when displaying FLI or FLC
  1367. files. Example 9-13 shows how to display a PCX image stored in the fg_imagebuf
  1368. buffer.
  1369.  
  1370.                                  Example 9-13.
  1371.  
  1372.                #include <fastgraf.h>
  1373.                #include <io.h>
  1374.                #include <stdio.h>
  1375.                #include <stdlib.h>
  1376.                void main(void);
  1377.  
  1378.                #ifdef FG32
  1379.                char buffer[20000];
  1380.                #else
  1381.                char far buffer[20000];
  1382.                #endif
  1383.  
  1384.                void main()
  1385.                {
  1386.                   int file_size;
  1387.                   int old_mode;
  1388.                   FILE *stream;
  1389.  
  1390.                   fg_initpm();
  1391.                   if (fg_testmode(19,1) == 0) {                                
  1392. 208   Fastgraph User's Guide
  1393.  
  1394.                      printf("This program requires a 320 ");
  1395.                      printf("x 200 MCGA graphics mode.\n");
  1396.                      exit(1);
  1397.                      }
  1398.  
  1399.                   stream = fopen("CORAL.PCX","rb");
  1400.                   file_size = (int)(filelength(fileno(stream)));
  1401.                   fread(buffer,1,file_size,stream);
  1402.                   fclose(stream);
  1403.  
  1404.                   old_mode = fg_getmode();
  1405.                   fg_setmode(19);
  1406.  
  1407.                   fg_imagebuf(buffer,file_size);
  1408.                   fg_showpcx("",4);
  1409.                   fg_waitkey();
  1410.  
  1411.                   fg_setmode(old_mode);
  1412.                   fg_reset();
  1413.                }
  1414.  
  1415.  
  1416.      In example 9-13, we use a 20,000-byte array for the fg_imagebuf buffer.
  1417. The array used with fg_imagebuf must be large enough to hold the entire image
  1418. file. Note that we pass the actual file size to fg_imagebuf (in this example,
  1419. we assume the file size does not exceed 20,000 bytes). It is crucial that you
  1420. specify the actual file size when displaying 256-color PCX files so Fastgraph
  1421. can locate the extended (256-color) palette data that might follow the image
  1422. data. You must also specify the actual file size when using Fastgraph's low-
  1423. level flic support routines to play flic images from the fg_imagebuf buffer.
  1424. For other types of image files, we can specify either the file size or the
  1425. buffer size.
  1426.  
  1427.      It's not necessary to pass a file name to the image display routines the
  1428. image data resides in the fg_imagebuf buffer. In other words, the image
  1429. display routines ignore the file name argument when bit 2 of the flags
  1430. argument is set. However, you must still include a "place holder" argument
  1431. where a file name would otherwise be expected. We recommend using the null
  1432. string as in the fg_showpcx call of example 9-13, although any string can be
  1433. used instead.
  1434.  
  1435.      The maximum size of the image file we can display from the fg_imagebuf
  1436. buffer is of course limited to the buffer size. While this isn't in issue in
  1437. 32-bit protected mode, it does impose an important restriction in real mode
  1438. and 16-bit protected mode. The size of the fg_imagebuf buffer is limited to
  1439. 64K bytes in 16-bit environments, meaning this feature applies only to image
  1440. files that are 64K or less if you're using real mode or 16-bit protected mode.
  1441.  
  1442.  
  1443. Summary of Image File Routines
  1444.  
  1445.      This section summarizes the functional descriptions of the Fastgraph
  1446. routines presented in this chapter. More detailed information about these
  1447. routines, including their arguments and return values, may be found in the
  1448. Fastgraph Reference Manual. The image display and creation functions apply
  1449. only to graphics video modes.                                                  
  1450.                                                  Chapter 9:  Image Files   209
  1451.  
  1452.  
  1453.      FG_DISPFILE displays an image stored in a standard or packed pixel run
  1454. file. The image is positioned so that its lower left corner is at the current
  1455. graphics position.
  1456.  
  1457.      FG_FLICDONE closes the flic file associated with the specified context
  1458. descriptor.
  1459.  
  1460.      FG_FLICHEAD reads a flic file header into a 128-byte buffer.
  1461.  
  1462.      FG_FLICMODE determines the optimal video mode for the flic image
  1463. associated with the specified flic file header. The optimal mode is the 256-
  1464. color graphics mode having the lowest resolution larger than or equal to the
  1465. image dimensions.
  1466.  
  1467.      FG_FLICOPEN opens a flic file for subsequent processing by Fastgraph's
  1468. other low-level flic file support routines. If successful, the file pointer
  1469. will be positioned at the beginning of the first frame.
  1470.  
  1471.      FG_FLICPLAY displays the next one or more frames in a flic file
  1472. previously opened with fg_flicopen.
  1473.  
  1474.      FG_FLICSIZE returns the dimensions for the flic image associated with the
  1475. specified flic file header.
  1476.  
  1477.      FG_FLICSKIP advances one or more frames in a flic file previously opened
  1478. with fg_flicopen. If the last frame played by fg_flicplay displayed the frame
  1479. from the fg_imagebuf buffer, the frame position will be adjusted in the
  1480. fg_imagebuf buffer. Otherwise, the flic file position itself will be adjusted.
  1481.  
  1482.      FG_GIFHEAD reads the GIF file's global header and first local header into
  1483. a 23-byte buffer.
  1484.  
  1485.      FG_GIFMODE determines the optimal video mode for displaying a GIF file.
  1486. The optimal mode is the video mode having the lowest resolution larger than or
  1487. equal to the image dimensions.
  1488.  
  1489.      FG_GIFPAL retrieves the palette of an image stored in a GIF file. The
  1490. palette values are returned as RGB color components, each between 0 and 63. If
  1491. the GIF file includes a local palette for the first image, fg_gifpal will
  1492. return the values from the local palette. Otherwise, fg_gifpal will return the
  1493. values from the GIF file's global palette.
  1494.  
  1495.      FG_GIFRANGE returns the image extents for the GIF image associated with
  1496. the specified GIF file header.
  1497.  
  1498.      FG_IMAGEBUF specifies the size and address of the buffer used internally
  1499. when creating or displaying GIF, PCX, FLI/FLC, or SPR/PPR files. Fastgraph's
  1500. default internal buffer size is 4,096 bytes. Image display or creation is
  1501. typically faster when a larger buffer is used, especially in protected mode or
  1502. when playing flic files. In 16-bit environments, the size of the fg_imagebuf
  1503. buffer is limited to 64K bytes.
  1504.  
  1505.      FG_LOADPCX loads a PCX image into the active virtual buffer.              
  1506. 210   Fastgraph User's Guide
  1507.  
  1508.      FG_MAKEGIF creates a GIF file from the specified rectangular region of
  1509. the active video page or virtual buffer. The region's extremes are expressed
  1510. in screen space units. This routine is meaningful only in 16-color and 256-
  1511. color graphics modes.
  1512.  
  1513.      FG_MAKEPCX creates a PCX file from the specified rectangular region of
  1514. the active video page or virtual buffer. The region's extremes are expressed
  1515. in screen space units.
  1516.  
  1517.      FG_MAKEPPR creates a packed pixel run file from the specified rectangular
  1518. region of the active video page or virtual buffer. The region's extremes are
  1519. expressed in screen space units.
  1520.  
  1521.      FG_MAKESPR creates a standard pixel run file from the specified
  1522. rectangular region of the active video page or virtual buffer. The region's
  1523. extremes are expressed in screen space units.
  1524.  
  1525.      FG_PATTERN defines a display pattern for use when displaying pixel run
  1526. files in video modes that offer 16 or less colors.
  1527.  
  1528.      FG_PCXHEAD reads a PCX file header into a 128-byte buffer.
  1529.  
  1530.      FG_PCXMODE determines the optimal video mode for displaying a PCX file.
  1531. The optimal mode is the compatible video mode having the lowest resolution
  1532. larger than or equal to the image dimensions.
  1533.  
  1534.      FG_PCXPAL retrieves the palette of an image stored in a PCX file. The
  1535. palette values are returned as RGB color components, each between 0 and 63. If
  1536. the PCX file includes an extended (256-color) palette, fg_pcxpal will return
  1537. the values in the extended palette. Otherwise, fg_pcxpal will return the
  1538. values from the 16-color palette in the PCX header.
  1539.  
  1540.      FG_PCXRANGE returns the image extents for the PCX image associated with
  1541. the specified PCX file header.
  1542.  
  1543.      FG_SHOWGIF displays an image stored in a GIF file.
  1544.  
  1545.      FG_SHOWFLIC displays an image stored in an FLI or FLC file (collectively
  1546. called flic files).
  1547.  
  1548.      FG_SHOWPCX displays an image stored in a PCX file.
  1549.  
  1550.      FG_SHOWPPR displays an image stored in a packed pixel run file. The image
  1551. will be positioned so its lower left corner is at the graphics cursor position
  1552. of the active video page or virtual buffer.
  1553.  
  1554.      FG_SHOWSPR displays an image stored in a standard pixel run file. The
  1555. image will be positioned so its lower left corner is at the graphics cursor
  1556. position of the active video page or virtual buffer.
  1557.